home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_gnats.idb / usr / freeware / info / send-pr.info.z / send-pr.info (.txt)
GNU Info File  |  1999-04-16  |  61KB  |  1,281 lines
  1. This is Info file send-pr.info, produced by Makeinfo version 1.67 from
  2. the input file ./send-pr.texi.
  3. START-INFO-DIR-ENTRY
  4. * send-pr::                     Reporting problems--using send-pr
  5. END-INFO-DIR-ENTRY
  6.    Copyright (C) 1993 Free Software Foundation, Inc.
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.    Permission is granted to copy and distribute modified versions of
  11. this manual under the conditions for verbatim copying, provided also
  12. that the entire resulting derived work is distributed under the terms
  13. of a permission notice identical to this one.
  14.    Permission is granted to copy and distribute translations of this
  15. manual into another language, under the above conditions for modified
  16. versions.
  17. File: send-pr.info,  Node: Top,  Next: send-pr in detail,  Up: (dir)
  18. Overview
  19. ********
  20.    This manual documents `send-pr', version 3.2, which uses electronic
  21. mail to submit support questions and problem reports to a central
  22. Support Site.  No body of work is perfect, and support organizations
  23. understand this; `send-pr' is designed to allow users who have problems
  24. to submit reports of these problems to sites responsible for supporting
  25. the products in question, in a defined form which can be read by an
  26. electronically managed database.
  27.    `send-pr' is part of a suite of programs known collectively as
  28. GNATS, the GNU Problem Report Management System.  GNATS consists of
  29. several programs which, used in concert, formulate and partially
  30. administer a database of "Problem Reports", or "PRs", at a central
  31. Support Site.  A PR goes through several states in its lifetime; GNATS
  32. tracks the PR and all information associated with it through each state
  33. and finally acts as an archive for PRs which have been "closed".
  34.    Because `send-pr' exists as a shell (`/bin/sh') script and as an
  35. Elisp file for use with GNU Emacs, it can be used from any machine on
  36. your network which can run a shell script and/or Emacs.
  37.    In general, you can use any editor and mailer to submit valid Problem
  38. Reports, as long as the format required by GNATS is preserved.
  39. `send-pr' automates the process, however, and ensures that certain
  40. fields necessary for automatic processing are present.  `send-pr' is
  41. strongly recommended for all initial problem-oriented correspondence
  42. with your Support Site.  The organization you submit Problem Reports to
  43. supplies an address to which further information can be sent; the person
  44. responsible for the category of the problem you report contacts you
  45. directly.
  46. * Menu:
  47. * send-pr in detail::     Details about send-pr and GNATS
  48. * Invoking send-pr::      Editing and sending PRs
  49. * An Example::            A working example
  50. * Installing send-pr::    Installing send-pr on your system
  51. * Index::
  52. File: send-pr.info,  Node: send-pr in detail,  Next: Invoking send-pr,  Prev: Top,  Up: Top
  53. Details about send-pr and GNATS
  54. *******************************
  55.    A "Problem Report" is a message that describes a problem you are
  56. having with a body of work.  `send-pr' organizes this message into a
  57. form which can be understood and automatically processed by GNATS, the
  58. GNU Problem Report Management System.  A Problem Report is organized
  59. into "fields" which contain data describing you, your organization, and
  60. the problem you are announcing (*note Problem Report format: Fields.).
  61. Problem Reports go through several defined states in their lifetimes,
  62. from "open" to "closed" (*note States of Problem Reports: States.).
  63. * Menu:
  64. * States::                     States of Problem Reports
  65. * Fields::                     Problem Report format
  66. File: send-pr.info,  Node: States,  Next: Fields,  Up: send-pr in detail
  67. States of Problem Reports
  68. =========================
  69.    Each PR goes through a defined series of states between origination
  70. and closure.  The originator of a PR receives notification
  71. automatically of any state changes.
  72. "open"
  73.      The initial state of a Problem Report.  This means the PR has been
  74.      filed and the responsible person(s) notified.
  75. "analyzed"
  76.      The responsible person has analyzed the problem.  The analysis
  77.      should contain a preliminary evaluation of the problem and an
  78.      estimate of the amount of time and resources necessary to solve
  79.      the problem.  It should also suggest possible workarounds.
  80. "feedback"
  81.      The problem has been solved, and the originator has been given a
  82.      patch or other fix.  The PR remains in this state until the
  83.      originator acknowledges that the solution works.
  84. "closed"
  85.      A Problem Report is closed ("the bug stops here") only when any
  86.      changes have been integrated, documented, and tested, and the
  87.      submitter has confirmed the solution.
  88. "suspended"
  89.      Work on the problem has been postponed.  This happens if a timely
  90.      solution is not possible or is not cost-effective at the present
  91.      time.  The PR continues to exist, though a solution is not being
  92.      actively sought.  If the problem cannot be solved at all, it
  93.      should be closed rather than suspended.
  94. File: send-pr.info,  Node: Fields,  Prev: States,  Up: send-pr in detail
  95. Problem Report format
  96. =====================
  97.    The format of a PR is designed to reflect the nature of GNATS as a
  98. database.  Information is arranged into "fields", and kept in
  99. individual records (Problem Reports).
  100.    Problem Report fields are denoted by a keyword which begins with `>'
  101. and ends with `:', as in `>Confidential:'.  Fields belong to one of
  102. three data types:
  103. ENUMERATED
  104.      One of a specific set of values, which vary according to the
  105.      field.  The value for each keyword must be on the same line as the
  106.      keyword.  These values are not configurable (yet).
  107.      For each ENUMERATED keyword, the possible choices are listed in the
  108.      `send-pr' template as a comment.  The following fields are
  109.      ENUMERATED format; see the descriptions of fields below for
  110.      explanations of each field in detail:
  111.           >Confidential:   >Severity:       >Priority:
  112.           >Class:          >State:          >Number:
  113.      One single line of text which must begin and end on the same line
  114.      (i.e., before a newline) as the keyword.  See the descriptions of
  115.      fields below for explanations of each field in detail.  The
  116.      following fields are TEXT format:
  117.           >Submitter-Id:   >Originator:     >Synopsis:
  118.           >Category:       >Release:        >Responsible:
  119.           >Arrival-Date:
  120. MULTITEXT
  121.      Text of any length may occur in this field.  MULTITEXT may span
  122.      multiple lines and may also include blank lines.  A MULTITEXT field
  123.      ends only when another keyword appears.  See the descriptions of
  124.      fields below for explanations of each field in detail.
  125.      The following fields are MULTITEXT format:
  126.           >Organization:   >Environment:    >Description:
  127.           >How-To-Repeat:  >Fix:            >Audit-Trail:
  128.           >Unformatted:
  129.    A Problem Report contains two different types of fields: "Mail
  130. Header" fields, which are used by the mail handler for delivery, and
  131. "Problem Report" fields, which contain information relevant to the
  132. Problem Report and its submitter.  A Problem Report is essentially a
  133. specially formatted electronic mail message.
  134.    The following is an example Problem Report.  Mail headers are at the
  135. top, followed by GNATS fields, which begin with `>' and end with `:'.
  136. The `Subject:' line in the mail header and the `>Synopsis:' field are
  137. usually duplicates of each other.
  138.      Message-Id:  MESSAGE-ID
  139.      Date:        DATE
  140.      From:        ADDRESS
  141.      Reply-To:    ADDRESS
  142.      To:          BUG-ADDRESS
  143.      Subject:     SUBJECT
  144.      
  145.      >Number:       GNATS-ID
  146.      >Category:     CATEGORY
  147.      >Synopsis:     SYNOPSIS
  148.      >Confidential: yes *or* no
  149.      >Severity:     critical, serious, *or* non-critical
  150.      >Priority:     high, medium *or* low
  151.      >Responsible:  RESPONSIBLE
  152.      >State:        open, analyzed, suspended, feedback, *or* closed
  153.      >Class:        sw-bug, doc-bug, change-request, support,
  154.      *or* duplicate
  155.      >Submitter-Id: SUBMITTER-ID
  156.      >Arrival-Date: DATE
  157.      >Originator:   NAME
  158.      >Organization: ORGANIZATION
  159.      >Release:      RELEASE
  160.      >Environment:
  161.         ENVIRONMENT
  162.      >Description:
  163.         DESCRIPTION
  164.      >How-To-Repeat:
  165.         HOW-TO-REPEAT
  166.      >Fix:
  167.         FIX
  168.      >Audit-Trail:
  169.      APPENDED-MESSAGES...
  170.      State-Changed-From-To: FROM-TO
  171.      State-Changed-When: DATE
  172.      State-Changed-Why:
  173.         REASON
  174.      Responsible-Changed-From-To: FROM-TO
  175.      Responsible-Changed-When: DATE
  176.      Responsible-Changed-Why:
  177.         REASON
  178.      >Unformatted:
  179.         MISCELLANEOUS
  180. * Menu:
  181. * Mail header fields::
  182. * Problem Report fields::
  183. File: send-pr.info,  Node: Mail header fields,  Next: Problem Report fields,  Up: Fields
  184. Mail header fields
  185. ------------------
  186.    A Problem Report may contain any mail header field described in the
  187. Internet standard RFC-822.  However, only the fields which identify the
  188. sender and the subject are required by `send-pr':
  189. `To:'
  190.      The preconfigured mail address for the Support Site where the PR
  191.      is to be sent, automatically supplied by `send-pr'.
  192. `Subject:'
  193.      A terse description of the problem.  This field normally contains
  194.      the same information as the `>Synopsis:' field.
  195. `From:'
  196.      Usually supplied automatically by the originator's mailer; should
  197.      contain the originator's electronic mail address.
  198. `Reply-To:'
  199.      A return address to which electronic replies can be sent; in most
  200.      cases, the same address as the `From:' field.
  201. File: send-pr.info,  Node: Problem Report fields,  Prev: Mail header fields,  Up: Fields
  202. Problem Report fields
  203. ---------------------
  204. Field descriptions
  205. ------------------
  206.    The following fields are present whenever a PR is submitted via the
  207. program `send-pr'.  GNATS adds additional fields when the PR arrives at
  208. the Support Site; explanations of these follow this list.
  209. `>Submitter-Id:'
  210.      (TEXT) A unique identification code assigned by the Support Site.
  211.      It is used to identify all Problem Reports coming from a particular
  212.      site.  (Submitters without a value for this field can invoke
  213.      `send-pr' with the `--request-id' option to apply for one from the
  214.      support organization.  Problem Reports from those not affiliated
  215.      with the support organization should use the default value of `net'
  216.      for this field.)
  217. `>Originator:'
  218.      (TEXT) Originator's real name.  The default is the value of the
  219.      originator's environment variable `NAME'.
  220. `>Organization:'
  221.      (MULTITEXT) The originator's organization.  The default value is
  222.      set with the variable `DEFAULT_ORGANIZATION' in the `send-pr'
  223.      shell script.
  224. `>Confidential:'
  225.      (ENUMERATED) Use of this field depends on the originator's
  226.      relationship with the support organization; contractual agreements
  227.      often have provisions for preserving confidentiality.  Conversely,
  228.      a lack of a contract often means that any data provided will not
  229.      be considered confidential.  Submitters should be advised to
  230.      contact the support organization directly if this is an issue.
  231.      If the originator's relationship to the support organization
  232.      provides for confidentiality, then if the value of this field is
  233.      `yes' the support organization treats the PR as confidential; any
  234.      code samples provided are not made publicly available (e.g., in
  235.      regression test suites).  The default value is `yes'.
  236. `>Synopsis:'
  237.      (TEXT) One-line summary of the problem.  `send-pr' copies this
  238.      information to the `Subject:' line when you submit a Problem
  239.      Report.
  240. `>Severity:'
  241.      (ENUMERATED) The severity of the problem.  Accepted values include:
  242.     `critical'
  243.           The product, component or concept is completely
  244.           non-operational or some essential functionality is missing.
  245.           No workaround is known.
  246.     `serious'
  247.           The product, component or concept is not working properly or
  248.           significant functionality is missing.  Problems that would
  249.           otherwise be considered `critical' are rated `serious' when a
  250.           workaround is known.
  251.     `non-critical'
  252.           The product, component or concept is working in general, but
  253.           lacks features, has irritating behavior, does something
  254.           wrong, or doesn't match its documentation.  The default value
  255.      is `serious'.
  256. `>Priority:'
  257.      (ENUMERATED) How soon the originator requires a solution.  Accepted
  258.      values include:
  259.     `high'
  260.           A solution is needed as soon as possible.
  261.     `medium'
  262.           The problem should be solved in the next release.
  263.     `low'
  264.           The problem should be solved in a future release.
  265.      The default value is `medium'.
  266. `>Category:'
  267.      (TEXT) The name of the product, component or concept where the
  268.      problem lies.  The values for this field are defined by the Support
  269.      Site.
  270. `>Class:'
  271.      (ENUMERATED) The class of a problem can be one of the following:
  272.     `sw-bug'
  273.           A general product problem.  (`sw' stands for "software".)
  274.     `doc-bug'
  275.           A problem with the documentation.
  276.     `change-request'
  277.           A request for a change in behavior, etc.
  278.     `support'
  279.           A support problem or question.
  280.     `duplicate (PR-NUMBER)'
  281.           Duplicate PR.  PR-NUMBER should be the number of the original
  282.           PR.
  283.      The default is `sw-bug'.
  284. `>Release:'
  285.      (TEXT) Release or version number of the product, component or
  286.      concept.
  287. `>Environment:'
  288.      (MULTITEXT) Description of the environment where the problem
  289.      occured: machine architecture, operating system, host and target
  290.      types, libraries, pathnames, etc.
  291. `>Description:'
  292.      (MULTITEXT) Precise description of the problem.
  293. `>How-To-Repeat:'
  294.      (MULTITEXT) Example code, input, or activities to reproduce the
  295.      problem.  The support organization uses example code both to
  296.      reproduce the problem and to test whether the problem is fixed.
  297.      Include all preconditions, inputs, outputs, conditions after the
  298.      problem, and symptoms.  Any additional important information
  299.      should be included.  Include all the details that would be
  300.      necessary for someone else to recreate the problem reported,
  301.      however obvious.  Sometimes seemingly arbitrary or obvious
  302.      information can point the way toward a solution.  See also *Note
  303.      Helpful hints: Helpful hints.
  304. `>Fix:'
  305.      (MULTITEXT) A description of a solution to the problem, or a patch
  306.      which solves the problem.  (This field is most often filled in at
  307.      the Support Site; we provide it to the submitter in case she has
  308.      solved the problem.)
  309. GNATS adds the following fields when the PR arrives at the Support Site:
  310. `>Number:'
  311.      (ENUMERATED) The incremental identification number for this PR.
  312.      The `>Number:' field is often paired with the `>Category:' field as
  313.           CATEGORY/NUMBER
  314.      in subsequent email messages.  This is for historical reasons, as
  315.      well as because Problem Reports are stored in subdirectories which
  316.      are named by category.
  317. `>State:'
  318.      (ENUMERATED) The current state of the PR.  Accepted values are:
  319.     `open'
  320.           The PR has been filed and the responsible person notified.
  321.     `analyzed'
  322.           The responsible person has analyzed the problem.
  323.     `feedback'
  324.           The problem has been solved, and the originator has been
  325.           given a patch or other fix.
  326.     `closed'
  327.           The changes have been integrated, documented, and tested, and
  328.           the originator has confirmed that the solution works.
  329.     `suspended'
  330.           Work on the problem has been postponed.
  331.      The initial state of a PR is `open'.  *Note States of Problem
  332.      Reports: States.
  333. `>Responsible:'
  334.      (TEXT) The person responsible for this category.
  335. `>Arrival-Date:'
  336.      (TEXT) The time that this PR was received by GNATS.  The date is
  337.      provided automatically by GNATS.
  338. `>Audit-Trail:'
  339.      (MULTITEXT) Tracks related electronic mail as well as changes in
  340.      the `>State:' and `>Responsible:' fields with the sub-fields:
  341.     `State-Changed-<From>-<To>: OLDSTATE>-<NEWSTATE'
  342.           The old and new `>State:' field values.
  343.     `Responsible-Changed-<From>-<To>: OLDRESP>-<NEWRESP'
  344.           The old and new `>Responsible:' field values.
  345.     `State-Changed-By: NAME'
  346.     `Responsible-Changed-By: NAME'
  347.           The name of the maintainer who effected the change.
  348.     `State-Changed-When: TIMESTAMP'
  349.     `Responsible-Changed-When: TIMESTAMP'
  350.           The time the change was made.
  351.     `State-Changed-Why: REASON...'
  352.     `Responsible-Changed-Why: REASON...'
  353.           The reason for the change.
  354.      The `>Audit-Trail:' field also contains any mail messages received
  355.      by GNATS related to this PR, in the order received.
  356. `>Unformatted:'
  357.      (MULTITEXT) Any random text found outside the fields in the
  358.      original Problem Report.
  359. File: send-pr.info,  Node: Invoking send-pr,  Next: An Example,  Prev: send-pr in detail,  Up: Top
  360. Editing and sending PRs
  361. ***********************
  362.    You can invoke `send-pr' from a shell prompt or from within GNU
  363. Emacs using `M-x send-pr'.
  364. * Menu:
  365. * using send-pr::             Creating new Problem Reports
  366. * send-pr in Emacs::          Using send-pr from within Emacs
  367. * send-pr from the shell::    Invoking send-pr from the shell
  368. * Helpful hints::
  369. File: send-pr.info,  Node: using send-pr,  Next: send-pr in Emacs,  Up: Invoking send-pr
  370. Creating new Problem Reports
  371. ============================
  372.    Invoking `send-pr' presents a PR "template" with a number of fields
  373. already filled in.  Complete the template as thoroughly as possible to
  374. make a useful bug report.  Submit only one bug with each PR.
  375.    A template consists of three sections:
  376. "Comments"
  377.      The top several lines of a blank template consist of a series of
  378.      comments that provide some basic instructions for completing the
  379.      Problem Report, as well as a list of valid entries for the
  380.      `>Category:' field.  These comments are all preceded by the string
  381.      `SEND-PR:' and are erased automatically when the PR is submitted.
  382.      The instructional comments within `<' and `>' are also removed.
  383.      (Only these comments are removed; lines you provide that happen to
  384.      have those characters in them, such as examples of shell-level
  385.      redirection, are not affected.)
  386. "Mail Header"
  387.      `send-pr' creates a standard mail header.  `send-pr' completes all
  388.      fields except the `Subject:' line with default values.  (*Note
  389.      Problem Report format: Fields.)
  390. "GNATS fields"
  391.      These are the informational fields that GNATS uses to route your
  392.      Problem Report to the responsible party for further action.  They
  393.      should be filled out as completely as possible.  (*Note Problem
  394.      Report format: Fields.  Also see *Note Helpful hints: Helpful
  395.      hints.)
  396. For examples of a Problem Report template and complete Problem Report,
  397. see *Note An Example::.
  398.    The default template contains your preconfigured `>Submitter-Id:'.
  399. `send-pr' attempts to determine values for the `>Originator:' and
  400. `>Organization:' fields (*note Problem Report format: Fields.).
  401. `send-pr' also attempts to find out some information about your system
  402. and architecture, and places this information in the `>Environment:'
  403. field if it finds any.
  404.    You may submit problem reports to different Support Sites from the
  405. default site by specifying the alternate site when you invoke
  406. `send-pr'.  Each `site' has its own list of categories for which it
  407. accepts Problem Reports.  (*Note Setting a default SITE: default site.)
  408.    `send-pr' also provides the mail header section of the template with
  409. default values in the `To:', `From:', and `Reply-To:' fields.  The
  410. `Subject:' field is empty.
  411.    The template begins with a comment section:
  412.      SEND-PR: -*- send-pr  -*-
  413.      SEND-PR: Lines starting with `SEND-PR' will be removed
  414.      SEND-PR: automatically as well as all comments (the text
  415.      SEND-PR: below enclosed in `<' and `>').
  416.      SEND-PR:
  417.      SEND-PR: Please consult the document `Reporting Problems
  418.      SEND-PR: Using send-pr' if you are not sure how to fill out
  419.      SEND-PR: a problem report.
  420.      SEND-PR:
  421.      SEND-PR: Choose from the following categories:
  422. and also contains a list of valid `>Category:' values for the Support
  423. Site to whom you are submitting this Problem Report.  One (and only
  424. one) of these values should be placed in the `>Category:' field.  A
  425. complete sample bug report, from template to completed PR, is shown in
  426. *Note An Example::.  For a complete list of valid categories, type
  427. `send-pr -L' at your prompt.  *Note Valid Categories: Valid Categories,
  428. for a sample list of categories, .
  429.    The mail header is just below the comment section.  Fill out the
  430. `Subject:' field, if it is not already completed using the value of
  431. `>Synopsis:'.  The other mail header fields contain default values.
  432.      To: SUPPORT-SITE
  433.      Subject: *complete this field*
  434.      From: YOUR-LOGIN@YOUR-SITE
  435.      Reply-To: YOUR-LOGIN@YOUR-SITE
  436.      X-send-pr-version: send-pr 3.2
  437. where SUPPORT-SITE is an alias for the Support Site you wish to submit
  438. this PR to.
  439.    The rest of the template contains GNATS fields.  Each field is
  440. either automatically completed with valid information (such as your
  441. `>Submitter-Id:') or contains a one-line instruction specifying the
  442. information that field requires in order to be correct.  For example,
  443. the `>Confidential:' field expects a value of `yes' or `no', and the
  444. answer must fit on one line; similarly, the `>Synopsis:' field expects
  445. a short synopsis of the problem, which must also fit on one line.  Fill
  446. out the fields as completely as possible.  *Note Helpful hints: Helpful
  447. hints, for suggestions as to what kinds of information to include.
  448.    In this example, words in *italics* are filled in with
  449. pre-configured information:
  450.      >Submitter-Id: *your submitter-id*
  451.      >Originator:   *your name here*
  452.      >Organization:
  453.          *your organization*
  454.      >Confidential:<[ yes | no ] (one line)>
  455.      >Synopsis:    <synopsis of the problem (one line)>
  456.      >Severity:    <[non-critical | serious | critical](one line)>
  457.      >Priority:    <[ low | medium | high ] (one line)>
  458.      >Category:    <name of the product (one line)>
  459.      >Class:       <[sw-bug | doc-bug | change-request | support]>
  460.      >Release:     <release number or tag (one line)>
  461.      >Environment:
  462.               <machine, os, target, libraries (multiple lines)>
  463.      
  464.      >Description:
  465.             <precise description of the problem (multiple lines)>
  466.      >How-To-Repeat:
  467.             <code/input/activities to reproduce (multiple lines)>
  468.      >Fix:
  469.             <how to correct or work around the problem, if known
  470.              (multiple lines)>
  471.    When you finish editing the Problem Report, `send-pr' mails it to
  472. the address named in the `To:' field in the mail header.  `send-pr'
  473. checks that the complete form contains a valid `>Category:'.
  474.    Your copy of `send-pr' should have already been customized on
  475. installation to reflect your `>Submitter-Id:'.  (*Note Installing
  476. `send-pr' on your system: Installing send-pr.)  If you don't know your
  477. `>Submitter-Id:', you can request it using `send-pr --request-id'.  If
  478. your organization is not affiliated with the site you send Problem
  479. Reports to, a good generic `>Submitter-Id:' to use is `net'.
  480.    If your PR has an invalid value in one of the ENUMERATED fields
  481. (*note Problem Report format: Fields.), `send-pr' places the PR in a
  482. temporary file named `/tmp/pbadNNNN' on your machine.  NNNN is the
  483. process identification number given to your current `send-pr' session.
  484. If you are running `send-pr' from the shell, you are prompted as to
  485. whether or not you wish to try editing the same Problem Report again.
  486. If you are running `send-pr' from Emacs, the Problem Report is placed
  487. in the buffer `*send-pr-error*'; you can edit this file and then submit
  488. it with
  489.      M-x gnats-submit-pr
  490.    Any further mail concerning this Problem Report should be
  491. carbon-copied to the GNATS mailing address as well, with the category
  492. and identification number in the `Subject:' line of the message.
  493.      Subject: Re: PR CATEGORY/GNATS-ID: ORIGINAL MESSAGE SUBJECT
  494. Messages which arrive with `Subject:' lines of this form are
  495. automatically appended to the Problem Report in the `>Audit-Trail:'
  496. field in the order received.
  497. File: send-pr.info,  Node: send-pr in Emacs,  Next: send-pr from the shell,  Prev: using send-pr,  Up: Invoking send-pr
  498. Using `send-pr' from within Emacs
  499. =================================
  500.    You can use an interactive `send-pr' interface from within GNU Emacs
  501. to fill out your Problem Report.  We recommend that you familiarize
  502. yourself with Emacs before using this feature (*note Introduction:
  503. (emacs)Introduction.).
  504.    Call `send-pr' with `M-x send-pr'.(1)  `send-pr' responds with a
  505. Problem Report template preconfigured for the Support Site from which
  506. you received `send-pr'.  (If you use `send-pr' locally, the default
  507. Support Site is probably your local site.)
  508.    You may also submit problem reports to different Support Sites from
  509. the default site.  To use this feature, invoke `send-pr' with
  510.      C-u M-x send-pr
  511.    `send-pr' prompts you for the name of a SITE.  SITE is an alias on
  512. your local machine which points to an alternate Support Site.
  513.    `send-pr' displays the template and prompts you in the minibuffer
  514. with the line:
  515.      >Category: other
  516. Delete the default value `other' *in the minibuffer* and replace it
  517. with the keyword corresponding to your problem (the list of valid
  518. categories is in the topmost section of the PR template).  For example,
  519. if the problem you wish to report has to do with the GNU C compiler,
  520. and your support organization accepts bugs submitted for this program
  521. under the category `gcc', delete `other' and then type `gcc[<RET>]'.
  522. `send-pr' replaces the line
  523.      >Category:       <name of the product (one line)>
  524. in the template with
  525.      >Category:       gcc
  526. and moves on to another field.
  527.    `send-pr' provides name completion in the minibuffer.  For instance,
  528. you can also type `gc[<TAB>]', and `send-pr' attempts to complete the
  529. entry for you.  Typing `g[<TAB>]' may not have the same effect if
  530. several possible entries begin with `g'.  In that case `send-pr' cannot
  531. complete the entry because it cannot determine whether you mean `gcc'
  532. or, for example, `gdb', if both of those are possible categories.
  533. `send-pr' continues to prompt you for a valid entry until you enter one.
  534.    `send-pr' prompts you interactively to enter each field for which
  535. there is a range of specific choices.  If you attempt to enter a value
  536. which is not in the range of acceptable entries, `send-pr' responds
  537. with `[No match]' and allows you to change the entry until it contains
  538. an acceptable value.  This avoids unusable information (at least in
  539. these fields) and also avoids typographical errors which could cause
  540. problems later.
  541.    `send-pr' prompts you for the following fields:
  542.      >Category:
  543.      >Confidential: (*default*:  no)
  544.      >Severity:     (*default*:  serious)
  545.      >Priority:     (*default*:  medium)
  546.      >Class:        (*default*:  sw-bug)
  547.      >Release:
  548.      >Synopsis:     (*this value is copied to `Subject:'*)
  549. After you complete these fields, `send-pr' places the cursor in the
  550. `>Description:' field and displays the message
  551.      To send the problem report use: C-c C-c
  552. in the minibuffer.  At this point, edit the file in the main buffer to
  553. reflect your specific problem, putting relevant information in the
  554. proper fields.  *Note An Example::, for a sample Problem Report.
  555.    `send-pr' provides a few key bindings to make moving around in a
  556. template buffer more simple:
  557. `C-c C-f'
  558. `M-x change-field'
  559.      Changes the field under the cursor.  `edit-pr' prompts you for a
  560.      new value.
  561. `M-C-b'
  562. `M-x gnats-backward-field'
  563.      Moves the cursor to the beginning of the value of the current
  564.      field.
  565. `M-C-f'
  566. `M-x gnats-forward-field'
  567.      Moves the cursor to the end of the value of the current field.
  568. `M-p'
  569. `M-x gnats-previous-field'
  570.      Moves the cursor back one field to the beginning of the value of
  571.      the previous field.
  572. `M-n'
  573. `M-x gnats-next-field'
  574.      Moves the cursor forward one field to the beginning of the value
  575.      of the next field.
  576.    `send-pr' takes over again when you type `C-c C-c' to send the
  577. message.  `send-pr' reports any errors in a separate buffer, which
  578. remains in existence until you send the PR properly (or, of course,
  579. until you explicitly kill the buffer).
  580.    For detailed instructions on using Emacs, see *Note Introduction:
  581. (emacs)Introduction.
  582.    ---------- Footnotes ----------
  583.    (1)  If typing `M-x send-pr' doesn't work, see your system
  584. administrator for help loading `send-pr' into Emacs.
  585. File: send-pr.info,  Node: send-pr from the shell,  Next: Helpful hints,  Prev: send-pr in Emacs,  Up: Invoking send-pr
  586. Invoking `send-pr' from the shell
  587. =================================
  588.      send-pr [ SITE ]
  589.              [ -f PROBLEM-REPORT | --file PROBLEM-REPORT ]
  590.              [ -t MAIL-ADDRESS | --to MAIL-ADDRESS ]
  591.              [ --request-id ]
  592.              [ -L | --list ] [ -P | --print ]
  593.              [ -V | --version] [ -h | --help ]
  594.    SITE is an alias on your local machine which points to an address
  595. used by a Support Site.  If this argument is not present, the default
  596. SITE is usually the site which you received `send-pr' from, or your
  597. local site if you use GNATS locally.  (*Note Setting a default SITE:
  598. default site.)
  599.    Invoking `send-pr' with no options calls the editor named in your
  600. environment variable `EDITOR' on a default PR template.  If the
  601. environment variable `PR_FORM' is set, its value is used as a file name
  602. which contains a valid template.  If `PR_FORM' points to a missing or
  603. unreadable file, or if the file is empty, `send-pr' generates an error
  604. message and opens the editor on a default template.
  605. `-f PROBLEM-REPORT'
  606. `--file PROBLEM-REPORT'
  607.      Specifies a file, PROBLEM-REPORT, where a completed Problem Report
  608.      already exists.  `send-pr' sends the contents of the file without
  609.      invoking an editor.  If PROBLEM-REPORT is `-', `send-pr' reads
  610.      from standard input.
  611. `-t MAIL-ADDRESS'
  612. `--to MAIL-ADDRESS'
  613.      Sends the PR to MAIL-ADDRESS. The default is preset when `send-pr'
  614.      is configured.  *This option is not recommended*; instead, use the
  615.      argument SITE on the command line.
  616. `--request-id'
  617.      Sends a request for a `>Submitter-Id:' to the Support Site.
  618. `--list'
  619.      Prints the list of valid `>Category:' values on standard output.
  620.      No mail is sent.
  621. `--print'
  622.      Displays the PR template.  If the variable `PR_FORM' is set in your
  623.      environment, the file it specifies is printed.  If `PR_FORM' is not
  624.      set, `send-pr' prints the standard blank form.  If the file
  625.      specified by `PR_FORM' doesn't exist, `send-pr' displays an error
  626.      message.  No mail is sent.
  627. `--version'
  628.      Displays the `send-pr' version number and a usage summary.  No mail
  629.      is sent.
  630. `--help'
  631.      Displays a usage summary for `send-pr'.  No mail is sent.
  632. File: send-pr.info,  Node: Helpful hints,  Prev: send-pr from the shell,  Up: Invoking send-pr
  633. Helpful hints
  634. =============
  635.    There is no orthodox standard for submitting effective bug reports,
  636. though you might do well to consult the section on submitting bugs for
  637. GNU `gcc' in *Note Reporting Bugs: (gcc)Bugs, by Richard Stallman.
  638. This section contains instructions on what kinds of information to
  639. include and what kinds of mistakes to avoid.
  640.    In general, common sense (assuming such an animal exists) dictates
  641. the kind of information that would be most helpful in tracking down and
  642. resolving problems in software.
  643.    * Include anything *you* would want to know if you were looking at
  644.      the report from the other end.  There's no need to include every
  645.      minute detail about your environment, although anything that might
  646.      be different from someone else's environment should be included
  647.      (your path, for instance).
  648.    * Narratives are often useful, given a certain degree of restraint.
  649.      If a person responsible for a bug can see that A was executed, and
  650.      then B and then C, knowing that sequence of events might trigger
  651.      the realization of an intermediate step that was missing, or an
  652.      extra step that might have changed the environment enough to cause
  653.      a visible problem.  Again, restraint is always in order ("I set
  654.      the build running, went to get a cup of coffee (Columbian, cream
  655.      but no sugar), talked to Sheila on the phone, and then THIS
  656.      happened...") but be sure to include anything relevant.
  657.    * Richard Stallman writes, "The fundamental principle of reporting
  658.      bugs usefully is this: *report all the facts*.  If you are not sure
  659.      whether to state a fact or leave it out, state it!"  This holds
  660.      true across all problem reporting systems, for computer software
  661.      or social injustice or motorcycle maintenance.  It is especially
  662.      important in the software field due to the major differences
  663.      seemingly insignificant changes can make (a changed variable, a
  664.      missing semicolon, etc.).
  665.    * Submit only *one* problem with each Problem Report.  If you have
  666.      multiple problems, use multiple PRs.  This aids in tracking each
  667.      problem and also in analyzing the problems associated with a given
  668.      program.
  669.    * It never hurts to do a little research to find out if the bug
  670.      you've found has already been reported.  Most software releases
  671.      contain lists of known bugs in the Release Notes which come with
  672.      the software; see your system administrator if you don't have a
  673.      copy of these.
  674.    * The more closely a PR adheres to the standard format, the less
  675.      interaction is required by a database administrator to route the
  676.      information to the proper place.  Keep in mind that anything that
  677.      requires human interaction also requires time that might be better
  678.      spent in actually fixing the problem.  It is therefore in
  679.      everyone's best interest that the information contained in a PR be
  680.      as correct as possible (in both format and content) at the time of
  681.      submission.
  682. File: send-pr.info,  Node: An Example,  Next: Installing send-pr,  Prev: Invoking send-pr,  Up: Top
  683. An Example
  684. **********
  685.    Cygnus Support in Mountain View, CA, uses GNATS and `send-pr'
  686. extensively for their support activities.  As a support company, Cygnus
  687. finds problem tracking to be a crucial part of everyday business.
  688. Cygnus supports the GNU compiling tools (including GNATS and `send-pr')
  689. over several many platforms
  690.    With each shipment of the Cygnus Support Developer's Kit, customers
  691. receive the latest version of `send-pr', which contains an up-to-date
  692. listing of valid categories (values for the `>Category:' field).  Using
  693. these tools, Cygnus' customers can communicate their problems to Cygnus
  694. effectively and receive automatic confirmation of receipt as well as
  695. notification of changes in the status of their reported problems.  Much
  696. of Cygnus' support mechanism relies on electronic mail.
  697.    As an example, let's pretend we're a customer of Cygnus Support, and
  698. that we're having a problem compiling some of our software using the
  699. GNU C compiler, which Cygnus supports.
  700.    Assume that we're getting an error in our `bifrabulator' program
  701. wherein the `prestidigitation' routines don't match with the
  702. `whatsitsname'.  We've made sure we're following the rules of the
  703. program and checked the Release Notes from Cygnus and found that the bug
  704. isn't already known.  In other words, we're pretty sure we've found a
  705.    Our first step is to call `send-pr'.  It really doesn't matter
  706. whether we use `send-pr' from the shell or from within Emacs.  Indeed,
  707. if we use Emacs as a primary editor, calling `send-pr' from the shell
  708. is likely to start `send-pr' in an Emacs buffer anyway.  So, since our
  709. company, *Imaginary Software, Ltd.*, uses GNU software extensively,
  710. we're pretty familiar with Emacs, so from within Emacs we type
  711.      M-x send-pr
  712. and we're greeted with the following screen:
  713.      SEND-PR: -*- text  -*-
  714.      SEND-PR: Lines starting with `SEND-PR' will be removed
  715.      SEND-PR: automatically as well as all comments (the text
  716.      SEND-PR: below enclosed in `<' and `>').
  717.      SEND-PR: Please consult the manual if you are not sure
  718.      SEND-PR: how to fill out a problem report.
  719.      SEND-PR:
  720.      SEND-PR: Choose from the following categories:
  721.      SEND-PR:
  722.      SEND-PR:           bfd       binutils  bison
  723.      SEND-PR: byacc     clib      config    cvs         diff
  724.      SEND-PR: doc       emacs     flex      g++         gas
  725.      SEND-PR: gcc       gdb       glob      gprof       grep
  726.      SEND-PR: info      ispell    kerberos  ld          libg++
  727.      SEND-PR: libiberty make      makeinfo  mas         newlib
  728.      SEND-PR: other     patch     rcs       readline    send-pr
  729.      SEND-PR: test      texindex  texinfo   texinfo.tex
  730.      SEND-PR: bifrabulator  <---*note: this one is fake*
  731.      SEND-PR:
  732.      To: cygnus-bugs@cygnus.com
  733.      Subject:
  734.      From: jeffrey@imaginary.com
  735.      Reply-To: jeffrey@imaginary.com
  736.      X-send-pr-version: send-pr 3.2
  737.      
  738.      >Submitter-Id:  imaginary
  739.      >Originator:    Jeffrey Osier
  740.      >Organization:
  741.      Imaginary Software, Ltd.
  742.      >Confidential:  <[ yes | no ] (one line)>
  743.      >Synopsis:      <synopsis of the problem (one line)>
  744.      >Severity:      <[ non-critical | serious | critical ] (one line)>
  745.      >Priority:      <[ low | medium | high ] (one line)>
  746.      >Category:      <name of the product (one line)>
  747.      >Class:         <[sw-bug|doc-bug|change-request|support](oneline)>
  748.      >Release:       <release number or tag (one line)>
  749.      >Environment:
  750.               <machine, os, target, libraries (multiple lines)>
  751.      System: SunOS imaginary.com 4.1.1 1 sun4
  752.      Architecture: sun4
  753.      
  754.      >Description:
  755.             <precise description of the problem (multiple lines)>
  756.      >How-To-Repeat:
  757.             <code/input/activities to reproduce (multiple lines)>
  758.      >Fix:
  759.      -----Emacs: *send-pr*   (send-pr Fill)----All------------------
  760.      >Category: other[]
  761.    We know from past experience that we need to set certain information
  762. into each field, so we compile all the information we know about our
  763. problem.  We have some sample code which we know should work, even
  764. though it doesn't, so we'll include that.  Below is the completed PR;
  765. we send this using `C-c C-c'.  (The comments have been truncated).
  766.      SEND-PR: Lines starting with `SEND-PR' will be removed
  767.      SEND-PR: automatically as well as all comments (the text
  768.      SEND-PR: ...
  769.      SEND-PR:
  770.      To: cygnus-bugs@cygnus.com
  771.      Subject: bifrabulator routines don't match
  772.      From: jeffrey@imaginary.com
  773.      Reply-To: jeffrey@imaginary.com
  774.      X-send-pr-version: send-pr 3.2
  775.      
  776.      >Submitter-Id:  imaginary
  777.      >Originator:    Jeffrey Osier
  778.      >Organization:
  779.      Imaginary Software, Ltd.
  780.      >Confidential:  no
  781.      >Synopsis:      bifrabulator routines don't match
  782.      >Severity:      serious
  783.      >Priority:      medium
  784.      >Category:      bifrabulator
  785.      >Class:         sw-bug
  786.      >Release:       progressive-930101
  787.      >Environment:
  788.      System: SunOS imaginary.com 4.1.1 1 sun4
  789.      Architecture: sun4 (SPARC)
  790.      
  791.      >Description:
  792.         the following code I fed into the bifrabulator came back
  793.         with a strange error.  apparently, the prestidigitation
  794.         routine doesn't match with the whatsitsname in all cases.
  795.      
  796.      >How-To-Repeat:
  797.         call the bifrabulator on the following code.
  798.         *code sample...*
  799.      
  800.      >Fix:
  801.      -----Emacs: *send-pr*   (send-pr Fill)----All------------------
  802.      To send the problem report use: C-c C-c
  803.    We type `C-c C-c', and off it goes.  Now, we depend on Cygnus
  804. Support to figure out the answer to our problem.
  805.    Soon afterward, we get the following message from Cygnus:
  806.      From: gnats (GNATS management)
  807.      Sender: gnats-admin
  808.      Reply-To: hacker@cygnus.com
  809.      To: jeffrey@imaginary.com
  810.      Subject: Re: bifrabulator/1425: routines don't match
  811.      
  812.      Thank you very much for your problem report.
  813.      It has the internal identification: g++/1425.
  814.      The individual assigned to look at your bug is:  hacker
  815.      (F.B. Hacker)
  816.      
  817.      Category: bifrabulator
  818.      Responsible: hacker
  819.      Synopsis: bifrabulator routines don't match
  820.      Arrival-Date: Sat Feb 30 03:12:55 1993
  821. This is our receipt that the bug has been accepted and forwarded to the
  822. responsible party.
  823. A while later, we get the analysis:
  824.      To:  jeffrey@imaginary.com
  825.      From:  hacker@cygnus.com
  826.      Subject:  Re: bifrabulator/1425: routines don't match
  827.      Reply-To: hacker@cygnus.com
  828.      
  829.      Got your message, Jeff.  It seems that the bifrabulator was
  830.      confusing the prestidigitation routines with the realitychecker
  831.      when lexically parsing the whatsitsname.
  832.      
  833.      I'm working on robustisizing the bifrabulator now.
  834.      
  835.      How about lunch next week?
  836.      --
  837.      F.B. Hacker
  838.      Cygnus Support, Mountain View, CA  415 903 1400
  839.      #include <std-disclaimer.h>
  840. About the same time, we get another message from Cygnus.
  841.      From: hacker@cygnus.com
  842.      To:  jeffrey@imaginary.com
  843.      Subject:  Re: bifrabulator/1425: doesn't match prestidig
  844.      Reply-To:  hacker@cygnus.com
  845.      
  846.      
  847.                   `F.B. Hacker' changed the state to `analyzed'.
  848.      
  849.      State-Changed-From-To: open-analyzed
  850.      State-Changed-By: hacker
  851.      State-Changed-When: Fri Feb 31 1993 08:59:16 1993
  852.      State-Changed-Why:
  853.          figured out the problem, working on a patch this afternoon
  854.      --
  855.      F.B. Hacker
  856.      Cygnus Support, Mountain View, CA  415 903 1400
  857.      #include <std-disclaimer.h>
  858. The bug has now been analyzed, and Cygnus is working on a solution.
  859. Sometime later, we get more mail from F.B.:
  860.      To:  jeffrey@imaginary.com
  861.      From:  hacker@cygnus.com
  862.      Subject:  Re: bifrabulator/1425: routines don't match
  863.      Reply-To: hacker@cygnus.com
  864.      
  865.      There's a patch now that you can ftp over and check out.
  866.      
  867.      Hey, that joke you sent me was great!  The one about the
  868.      strings walking into a bar...  my boss laughed for an hour!
  869.      --
  870.      F.B. Hacker
  871.      Cygnus Support, Mountain View, CA  415 903 1400
  872.      #include <std-disclaimer.h>
  873.      From: hacker@cygnus.com
  874.      To:  jeffrey@imaginary.com
  875.      Subject:  Re: bifrabulator/1425: doesn't match prestidig
  876.      Reply-To:  hacker@cygnus.com
  877.      
  878.      
  879.                   `F.B. Hacker' changed the state to `feedback'.
  880.      
  881.      State-Changed-From-To: analyzed-feedback
  882.      State-Changed-By: hacker
  883.      State-Changed-When: Fri Feb 31 1993 23:43:16 1993
  884.      State-Changed-Why:
  885.          got the patch finished, notified Jeff at Imaginary Software
  886.      --
  887.      F.B. Hacker
  888.      Cygnus Support, Mountain View, CA  415 903 1400
  889.      #include <std-disclaimer.h>
  890. The bug has gone into "feedback" status now, until we get the patch,
  891. install it and test it.  When everything tests well, we can mail F.B.
  892. back and tell him the bug's been fixed, and he can change the state of
  893. the PR from "feedback" to "closed".
  894.    Following is a list of valid `>Category:' entries that are supported
  895. by Cygnus.
  896. * Menu:
  897. * Valid Categories::
  898. File: send-pr.info,  Node: Valid Categories,  Up: An Example
  899. Valid Categories
  900. ================
  901. `bfd'
  902.      GNU binary file descriptor library.
  903. `bifrabulator'
  904.      This one doesn't actually exist.
  905. `binutils'
  906.      GNU utilities for binary files (`ar', `nm', `size'...).
  907. `bison'
  908.      GNU parser generator.
  909. `byacc'
  910.      Free parser generator.
  911. `config'
  912.      Cygnus Support Software configuration and installation.
  913. `cvs'
  914.      Concurrent Version System.
  915. `diff'
  916.      GNU `diff' program.
  917. `doc'
  918.      Documentation and manuals.
  919. `emacs'
  920.      GNU Emacs editor and related functions.
  921. `flex'
  922.      GNU lexical analyzer.
  923. `g++'
  924.      GNU C++ compiler.
  925. `gas'
  926.      GNU assembler.
  927. `gcc'
  928.      GNU C compiler.
  929. `gdb'
  930.      GNU source code debugger.
  931. `glob'
  932.      The filename globbing functions.
  933. `gprof'
  934.      GNU profiler.
  935. `grep'
  936.      GNU `grep' program.
  937. `info'
  938.      GNU `info' hypertext reader.
  939. `ispell'
  940.      GNU spelling checker.
  941. `kerberos'
  942.      Kerberos authentication system.
  943.      GNU linker.
  944. `libc'
  945.      Cygnus Support C Support Library.
  946. `libg++'
  947.      GNU C++ class library.
  948. `libiberty'
  949.      GNU `libiberty' library.
  950. `libm'
  951.      Cygnus Support C Math Library.
  952. `make'
  953.      GNU `make' program.
  954. `makeinfo'
  955.      GNU utility to build Info files from Texinfo documents.
  956. `mas'
  957.      GNU Motorola syntax assembler.
  958. `newlib'
  959.      Cygnus Support C Support and Math Libraries.
  960. `patch'
  961.      GNU bug patch program.
  962. `gnats'
  963.      GNU Problem Report Management System.
  964. `rcs'
  965.      Revision Control System.
  966. `readline'
  967.      GNU `readline' library.
  968. `send-pr'
  969.      GNU Problem Report submitting program.
  970. `test'
  971.      Category to use when testing `send-pr'.
  972. `texindex'
  973.      GNU documentation indexing utility.
  974. `texinfo'
  975.      GNU documentation macros.
  976. `other'
  977.      Anything which is not covered by the above categories.
  978. File: send-pr.info,  Node: Installing send-pr,  Next: Index,  Prev: An Example,  Up: Top
  979. Installing `send-pr' on your system
  980. ***********************************
  981.    If you receive `send-pr' as part of a larger software distribution,
  982. it probably gets installed when the full distribution is installed.  If
  983. you are using GNATS at your site as well, you must decide where
  984. `send-pr' sends Problem Reports by default; see *Note Setting a default
  985. SITE: default site.
  986. * Menu:
  987. * installation::   installing `send-pr' by itself
  988. * default site::   setting a default site
  989. File: send-pr.info,  Node: installation,  Next: default site,  Up: Installing send-pr
  990. Installing `send-pr' by itself
  991. ==============================
  992.    Install `send-pr' by following these steps (you may need `root'
  993. access in order to change the `aliases' file and to install `send-pr'):
  994.    * Unpack the distribution into a directory which we refer to as
  995.      SRCDIR.
  996.    * Edit the file `Makefile' to reflect local conventions.
  997.      Specifically, you should edit the variable `prefix' to alter the
  998.      installation location.  The default is `/usr/local'.  All files are
  999.      installed under `prefix' (see below).
  1000.    * *Run*
  1001.           make all install [ info ] [ install-info ] [ clean ]
  1002.      The targets mean the following:
  1003.     `all'
  1004.           Builds `send-pr' and `install-sid'
  1005.     `install'
  1006.           Installs the following:
  1007.          `install-sid'
  1008.          `send-pr'
  1009.                into `PREFIX/bin'
  1010.          `send-pr.1'
  1011.                into `PREFIX/man/man1'
  1012.          `SITE'
  1013.                the list of valid CATEGORIES for the Support Site from
  1014.                which you received `send-pr', installed as
  1015.                `PREFIX/lib/gnats/SITE'
  1016.          `send-pr.el'
  1017.                into `PREFIX/lib/emacs/lisp'(1)
  1018.     `info (*optional*)'
  1019.           Builds `send-pr.info' from `send-pr.texi'
  1020.           (`send-pr.info' is included with this distribution)
  1021.     `install-info (*optional*)'
  1022.           Installs `send-pr.info' into `PREFIX/info'
  1023.     `clean (*optional*)'
  1024.           Removes all intermediary build files that can be rebuilt from
  1025.           source code
  1026.    * Run
  1027.           install-sid YOUR-SID
  1028.      where YOUR-SID is the identification code you received with
  1029.      `send-pr'.  `send-pr' automatically inserts this value into the
  1030.      template field `>Submitter-Id:'.  If you've downloaded `send-pr'
  1031.      from the Net, use `net' for this value.
  1032.    * Place the following line in `PREFIX/lib/emacs/lisp/default.el', or
  1033.      instruct your users to place the following line in their `.emacs'
  1034.      files:
  1035.           (autoload 'send-pr "send-pr" "Submit a Problem Report." t)
  1036.    * Create a mail alias for the Support Site from which you received
  1037.      `send-pr', and for every site with which you wish to use `send-pr'
  1038.      to communicate.  Each alias must have a suffix of `-gnats'.  The
  1039.      Support Site(s) will provide the correct addresses where these
  1040.      aliases should point.  For instance, edit your mail aliases file
  1041.      to contain something like:
  1042.           # support sites; for use with send-pr
  1043.           cygnus-gnats:     bugs@cygnus.com            # Cygnus Support
  1044.           bumblebee-gnats:  bumblebugs@bumblebee.com   # Bumblebee Inc.
  1045.           mycompany-gnats:  bugs@my.company.com (*if you use GNATS locally*)
  1046.      `send-pr' automatically searches for these aliases when you type
  1047.           send-pr cygnus
  1048.           send-pr bumblebee
  1049.           send-pr SITE...
  1050.      `send-pr' also uses SITE to determine the categories of problems
  1051.      accepted by the site in question by looking in
  1052.           PREFIX/lib/gnats/SITE
  1053.    ---------- Footnotes ----------
  1054.    (1)  If your main Emacs lisp repository is in a different directory
  1055. from this, substitute that directory for `PREFIX/lib/emacs/lisp'.
  1056. File: send-pr.info,  Node: default site,  Prev: installation,  Up: Installing send-pr
  1057. Setting a default SITE
  1058. ======================
  1059.    `send-pr' is capable of sending Problem Reports to any number of
  1060. Support Sites, using mail aliases which have `-gnats' appended them.
  1061. `send-pr' automatically appends the suffix, so that when you type
  1062.      send-pr SITE
  1063. the Problem Report goes to the address noted in the `aliases' file as
  1064. `SITE-gnats'.  You can do this in the Emacs version of `send-pr' by
  1065. invoking the program with
  1066.      C-u M-x send-pr
  1067. You are prompted for SITE.
  1068.    SITE is also used to error-check the `>Category:' field, as a
  1069. precaution against sending mistaken information (and against sending
  1070. information to the wrong site).
  1071.    You may also simply type
  1072.      send-pr
  1073. from the shell (or `M-x send-pr' in Emacs), and the Problem Report you
  1074. generate will be sent to the SITE, which is usually the site from which
  1075. you received your distribution of `send-pr'.  If you use GNATS at your
  1076. own organization, the default is usually your local address for
  1077. reporting problems.
  1078.    To change this, simply edit the file `Makefile' before installing
  1079. and change the line
  1080.      GNATS_SITE = SITE
  1081. to reflect the site where you wish to send PRs by default.
  1082. File: send-pr.info,  Node: Index,  Prev: Installing send-pr,  Up: Top
  1083. Index
  1084. *****
  1085. * Menu:
  1086. * *analyzed* state:                      States.
  1087. * *change-request* class:                Problem Report fields.
  1088. * *closed* state:                        States.
  1089. * *critical* severity problems:          Problem Report fields.
  1090. * *doc-bug* class:                       Problem Report fields.
  1091. * *duplicate* class:                     Problem Report fields.
  1092. * *Enumerated* data types:               Fields.
  1093. * *feedback* state:                      States.
  1094. * *high* priority problems:              Problem Report fields.
  1095. * *low* priority problems:               Problem Report fields.
  1096. * *medium* priority problems:            Problem Report fields.
  1097. * *MultiText* data types:                Fields.
  1098. * *non-critical* severity problems:      Problem Report fields.
  1099. * *open* state:                          States.
  1100. * *serious* severity problems:           Problem Report fields.
  1101. * *support* class:                       Problem Report fields.
  1102. * *suspended* state:                     States.
  1103. * *sw-bug* class:                        Problem Report fields.
  1104. * *Text* data types:                     Fields.
  1105. * >Arrival-Date::                        Problem Report fields.
  1106. * >Audit-Trail::                         Problem Report fields.
  1107. * >Category::                            Problem Report fields.
  1108. * >Class::                               Problem Report fields.
  1109. * >Confidential::                        Problem Report fields.
  1110. * >Description::                         Problem Report fields.
  1111. * >Environment::                         Problem Report fields.
  1112. * >Fix::                                 Problem Report fields.
  1113. * >How-To-Repeat::                       Problem Report fields.
  1114. * >Number::                              Problem Report fields.
  1115. * >Organization::                        Problem Report fields.
  1116. * >Originator::                          Problem Report fields.
  1117. * >Priority::                            Problem Report fields.
  1118. * >Release::                             Problem Report fields.
  1119. * >Responsible::                         Problem Report fields.
  1120. * >Severity::                            Problem Report fields.
  1121. * >State::                               Problem Report fields.
  1122. * >Submitter-Id: <1>:                    using send-pr.
  1123. * >Submitter-Id::                        Problem Report fields.
  1124. * >Synopsis::                            Problem Report fields.
  1125. * >Unformatted::                         Problem Report fields.
  1126. * an example:                            An Example.
  1127. * appending PRs <1>:                     using send-pr.
  1128. * appending PRs:                         Problem Report fields.
  1129. * Arrival-Date field:                    Problem Report fields.
  1130. * Audit-Trail field:                     Problem Report fields.
  1131. * automatic notification:                States.
  1132. * bad Problem Reports:                   using send-pr.
  1133. * bifrabulator:                          An Example.
  1134. * blank PR template:                     An Example.
  1135. * Category field:                        Problem Report fields.
  1136. * Class field:                           Problem Report fields.
  1137. * command line options:                  send-pr from the shell.
  1138. * comment section in the PR template:    using send-pr.
  1139. * completed Problem Report:              An Example.
  1140. * completion in Emacs:                   send-pr in Emacs.
  1141. * Confidential field:                    Problem Report fields.
  1142. * confidentiality in PRs:                Problem Report fields.
  1143. * Cygnus Support:                        An Example.
  1144. * database similarities:                 Fields.
  1145. * default PR template:                   An Example.
  1146. * default SITE:                          default site.
  1147. * Description field:                     Problem Report fields.
  1148. * details about send-pr:                 send-pr in detail.
  1149. * editing and sending PRs:               Invoking send-pr.
  1150. * effective problem reporting:           Helpful hints.
  1151. * Emacs:                                 send-pr in Emacs.
  1152. * Environment field:                     Problem Report fields.
  1153. * errors:                                using send-pr.
  1154. * example of a completed PR:             An Example.
  1155. * example of a default template:         An Example.
  1156. * example of a list of valid categories: Valid Categories.
  1157. * example of a state change:             An Example.
  1158. * example PR:                            An Example.
  1159. * example Problem Report:                Fields.
  1160. * field format:                          Problem Report fields.
  1161. * fields:                                Fields.
  1162. * fields - list:                         Problem Report fields.
  1163. * final state ("closed"):                States.
  1164. * Fix field:                             Problem Report fields.
  1165. * foreword to send-pr:                   Top.
  1166. * format:                                Fields.
  1167. * From: header:                          Mail header fields.
  1168. * generating new PRs:                    Invoking send-pr.
  1169. * GNATS:                                 Top.
  1170. * GNATS database fields:                 Problem Report fields.
  1171. * GNATS fields - list:                   Problem Report fields.
  1172. * GNU software support:                  An Example.
  1173. * helpful hints:                         Helpful hints.
  1174. * How-To-Repeat field:                   Problem Report fields.
  1175. * Imaginary Software, Ltd.:              An Example.
  1176. * information to submit:                 Helpful hints.
  1177. * initial state ("open"):                States.
  1178. * installation:                          Installing send-pr.
  1179. * installation procedure:                installation.
  1180. * interactive interface:                 send-pr in Emacs.
  1181. * Internet standard RFC-822:             Mail header fields.
  1182. * introduction to send-pr:               Top.
  1183. * invalid Problem Reports:               using send-pr.
  1184. * invoking send-pr:                      Invoking send-pr.
  1185. * invoking send-pr from Emacs:           send-pr in Emacs.
  1186. * invoking send-pr from the shell:       send-pr from the shell.
  1187. * kinds of helpful information:          Helpful hints.
  1188. * life-cycle of a Problem Report:        States.
  1189. * listing valid categories:              send-pr from the shell.
  1190. * mail header fields:                    Mail header fields.
  1191. * mail header section:                   using send-pr.
  1192. * name completion in Emacs:              send-pr in Emacs.
  1193. * Number field:                          Problem Report fields.
  1194. * Organization field:                    Problem Report fields.
  1195. * Originator field:                      Problem Report fields.
  1196. * other mail <1>:                        using send-pr.
  1197. * other mail:                            Problem Report fields.
  1198. * overview to send-pr:                   Top.
  1199. * PR confidentiality:                    Problem Report fields.
  1200. * Priority field:                        Problem Report fields.
  1201. * Problem Report data types:             Fields.
  1202. * Problem Report format:                 Fields.
  1203. * Problem Report states:                 States.
  1204. * Problem Report template:               Fields.
  1205. * Problem Reports:                       send-pr in detail.
  1206. * related mail <1>:                      Problem Report fields.
  1207. * related mail:                          using send-pr.
  1208. * Release field:                         Problem Report fields.
  1209. * Reply-To: header:                      Mail header fields.
  1210. * Report all the facts!:                 Helpful hints.
  1211. * Responsible field:                     Problem Report fields.
  1212. * Responsible-Changed-<From>-<To>: in >Audit-Trail:: Problem Report fields.
  1213. * Responsible-Changed-By: in >Audit-Trail:: Problem Report fields.
  1214. * Responsible-Changed-When: in >Audit-Trail:: Problem Report fields.
  1215. * Responsible-Changed-Why: in >Audit-Trail:: Problem Report fields.
  1216. * sample Problem Report:                 Fields.
  1217. * saving related mail <1>:               Problem Report fields.
  1218. * saving related mail:                   using send-pr.
  1219. * send-pr fields:                        using send-pr.
  1220. * send-pr within Emacs:                  send-pr in Emacs.
  1221. * sending PRs:                           Invoking send-pr.
  1222. * setting a default SITE:                default site.
  1223. * Severity field:                        Problem Report fields.
  1224. * shell invocation:                      send-pr from the shell.
  1225. * state change example:                  An Example.
  1226. * State field:                           Problem Report fields.
  1227. * state--"analyzed":                     States.
  1228. * state--"closed":                       States.
  1229. * state--"feedback":                     States.
  1230. * state--"open":                         States.
  1231. * state--"suspended":                    States.
  1232. * State-Changed-<From>-<To>: in >Audit-Trail:: Problem Report fields.
  1233. * State-Changed-By: in >Audit-Trail::    Problem Report fields.
  1234. * State-Changed-When: in >Audit-Trail::  Problem Report fields.
  1235. * State-Changed-Why: in >Audit-Trail::   Problem Report fields.
  1236. * states of Problem Reports:             States.
  1237. * Subject: header:                       Mail header fields.
  1238. * Submitter-Id field <1>:                Problem Report fields.
  1239. * Submitter-Id field:                    using send-pr.
  1240. * subsequent mail <1>:                   Problem Report fields.
  1241. * subsequent mail:                       using send-pr.
  1242. * Synopsis field:                        Problem Report fields.
  1243. * template:                              using send-pr.
  1244. * template comment section:              using send-pr.
  1245. * To: header:                            Mail header fields.
  1246. * Unformatted field:                     Problem Report fields.
  1247. * Using and Porting GNU CC:              Helpful hints.
  1248. * using send-pr:                         Invoking send-pr.
  1249. * using send-pr from within Emacs:       send-pr in Emacs.
  1250. * valid categories:                      Valid Categories.
  1251. Tag Table:
  1252. Node: Top
  1253. Node: send-pr in detail
  1254. Node: States
  1255. Node: Fields
  1256. Node: Mail header fields
  1257. Node: Problem Report fields
  1258. Node: Invoking send-pr
  1259. 17039
  1260. Node: using send-pr
  1261. 17496
  1262. Node: send-pr in Emacs
  1263. 24503
  1264. Node: send-pr from the shell
  1265. 28914
  1266. Node: Helpful hints
  1267. 31261
  1268. Node: An Example
  1269. 34366
  1270. Node: Valid Categories
  1271. 43466
  1272. Node: Installing send-pr
  1273. 45285
  1274. Node: installation
  1275. 45852
  1276. Node: default site
  1277. 49077
  1278. Node: Index
  1279. 50334
  1280. End Tag Table
  1281.